home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 85 / CD Actual 85 Febrero 2004.iso / Experto / Apache / apache_2.0.48-win32-x86-no_ssl.msi / Data.Cab / F251778_apr_thread_proc.h < prev    next >
Encoding:
C/C++ Source or Header  |  2003-06-19  |  33.1 KB  |  790 lines
  1. /* ====================================================================
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 2000-2003 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Apache" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  */
  54.  
  55. #ifndef APR_THREAD_PROC_H
  56. #define APR_THREAD_PROC_H
  57.  
  58. /**
  59.  * @file apr_thread_proc.h
  60.  * @brief APR Thread and Process Library
  61.  */
  62.  
  63. #include "apr.h"
  64. #include "apr_file_io.h"
  65. #include "apr_pools.h"
  66. #include "apr_errno.h"
  67.  
  68. #if APR_HAVE_STRUCT_RLIMIT
  69. #include <sys/time.h>
  70. #include <sys/resource.h>
  71. #endif
  72.  
  73. #ifdef __cplusplus
  74. extern "C" {
  75. #endif /* __cplusplus */
  76.  
  77. /**
  78.  * @defgroup apr_thread_proc Threads and Process Functions
  79.  * @ingroup APR 
  80.  * @{
  81.  */
  82.  
  83. typedef enum {
  84.     APR_SHELLCMD,       /**< use the shell to invoke the program */
  85.     APR_PROGRAM,        /**< invoke the program directly, no copied env */
  86.     APR_PROGRAM_ENV,    /**< invoke the program, replicating our environment */
  87.     APR_PROGRAM_PATH    /**< find program on PATH, use our environment */
  88. } apr_cmdtype_e;
  89.  
  90. typedef enum {
  91.     APR_WAIT,           /**< wait for the specified process to finish */
  92.     APR_NOWAIT          /**< do not wait -- just see if it has finished */
  93. } apr_wait_how_e;
  94.  
  95. /* I am specifically calling out the values so that the macros below make
  96.  * more sense.  Yes, I know I don't need to, but I am hoping this makes what
  97.  * I am doing more clear.  If you want to add more reasons to exit, continue
  98.  * to use bitmasks.
  99.  */
  100. typedef enum {
  101.     APR_PROC_EXIT = 1,          /**< process exited normally */
  102.     APR_PROC_SIGNAL = 2,        /**< process exited due to a signal */
  103.     APR_PROC_SIGNAL_CORE = 4    /**< process exited and dumped a core file */
  104. } apr_exit_why_e;
  105.  
  106. /** did we exit the process */
  107. #define APR_PROC_CHECK_EXIT(x)        (x & APR_PROC_EXIT)
  108. /** did we get a signal */
  109. #define APR_PROC_CHECK_SIGNALED(x)    (x & APR_PROC_SIGNAL)
  110. /** did we get core */
  111. #define APR_PROC_CHECK_CORE_DUMP(x)   (x & APR_PROC_SIGNAL_CORE)
  112.  
  113. /** @see apr_procattr_io_set */
  114. #define APR_NO_PIPE          0
  115.  
  116. /** @see apr_procattr_io_set */
  117. #define APR_FULL_BLOCK       1
  118. /** @see apr_procattr_io_set */
  119. #define APR_FULL_NONBLOCK    2
  120. /** @see apr_procattr_io_set */
  121. #define APR_PARENT_BLOCK     3
  122. /** @see apr_procattr_io_set */
  123. #define APR_CHILD_BLOCK      4
  124.  
  125. /** @see apr_procattr_limit_set */
  126. #define APR_LIMIT_CPU        0
  127. /** @see apr_procattr_limit_set */
  128. #define APR_LIMIT_MEM        1
  129. /** @see apr_procattr_limit_set */
  130. #define APR_LIMIT_NPROC      2
  131. /** @see apr_procattr_limit_set */
  132. #define APR_LIMIT_NOFILE     3
  133.  
  134. /**
  135.  * @defgroup APR_OC Other Child Flags
  136.  * @{
  137.  */
  138. #define APR_OC_REASON_DEATH         0     /**< child has died, caller must call
  139.                                            * unregister still */
  140. #define APR_OC_REASON_UNWRITABLE    1     /**< write_fd is unwritable */
  141. #define APR_OC_REASON_RESTART       2     /**< a restart is occuring, perform
  142.                                            * any necessary cleanup (including
  143.                                            * sending a special signal to child)
  144.                                            */
  145. #define APR_OC_REASON_UNREGISTER    3     /**< unregister has been called, do
  146.                                            * whatever is necessary (including
  147.                                            * kill the child) */
  148. #define APR_OC_REASON_LOST          4     /**< somehow the child exited without
  149.                                            * us knowing ... buggy os? */
  150. #define APR_OC_REASON_RUNNING       5     /**< a health check is occuring, 
  151.                                            * for most maintainence functions
  152.                                            * this is a no-op.
  153.                                            */
  154. /** @} */
  155.  
  156. /** The APR process type */
  157. typedef struct apr_proc_t {
  158.     /** The process ID */
  159.     pid_t pid;
  160.     /** Parent's side of pipe to child's stdin */
  161.     apr_file_t *in;
  162.     /** Parent's side of pipe to child's stdout */
  163.     apr_file_t *out;
  164.     /** Parent's side of pipe to child's stdouterr */
  165.     apr_file_t *err;
  166. #if APR_HAS_PROC_INVOKED || defined(DOXYGEN)
  167.     /** Diagnositics/debugging string of the command invoked for 
  168.      *  this process [only present if APR_HAS_PROC_INVOKED is true]
  169.      * @remark Only enabled on Win32 by default.
  170.      * @bug This should either always or never be present in release
  171.      * builds - since it breaks binary compatibility.  We may enable
  172.      * it always in APR 1.0 yet leave it undefined in most cases.
  173.      */
  174.     char *invoked;
  175. #endif
  176. #if defined(WIN32) || defined(DOXYGEN)
  177.     /** (Win32 only) Creator's handle granting access to the process
  178.      * @remark This handle is closed and reset to NULL in every case
  179.      * corresponding to a waitpid() on Unix which returns the exit status.
  180.      * Therefore Win32 correspond's to Unix's zombie reaping characteristics
  181.      * and avoids potential handle leaks.
  182.      */
  183.     HANDLE hproc;
  184. #endif
  185. } apr_proc_t;
  186.  
  187. /**
  188.  * The prototype for APR child errfn functions.  (See the description
  189.  * of apr_procattr_child_errfn_set() for more information.)
  190.  * It is passed the following parameters:
  191.  * @param pool Pool associated with the apr_proc_t.  If your child
  192.  *             error function needs user data, associate it with this
  193.  *             pool.
  194.  * @param err APR error code describing the error
  195.  * @param description Text description of type of processing which failed
  196.  */
  197. typedef void (apr_child_errfn_t)(apr_pool_t *proc, apr_status_t err,
  198.                                  const char *description);
  199.  
  200. /** Opaque Thread structure. */
  201. typedef struct apr_thread_t           apr_thread_t;
  202.  
  203. /** Opaque Thread attributes structure. */
  204. typedef struct apr_threadattr_t       apr_threadattr_t;
  205.  
  206. /** Opaque Process attributes structure. */
  207. typedef struct apr_procattr_t         apr_procattr_t;
  208.  
  209. /** Opaque control variable for one-time atomic variables.  */
  210. typedef struct apr_thread_once_t      apr_thread_once_t;
  211.  
  212. /** Opaque thread private address space. */
  213. typedef struct apr_threadkey_t        apr_threadkey_t;
  214.  
  215. /** Opaque record of child process. */
  216. typedef struct apr_other_child_rec_t  apr_other_child_rec_t;
  217.  
  218. /**
  219.  * The prototype for any APR thread worker functions.
  220.  */
  221. typedef void *(APR_THREAD_FUNC *apr_thread_start_t)(apr_thread_t*, void*);
  222.  
  223. typedef enum {
  224.     APR_KILL_NEVER,             /**< process is never sent any signals */
  225.     APR_KILL_ALWAYS,            /**< process is sent SIGKILL on apr_pool_t cleanup */
  226.     APR_KILL_AFTER_TIMEOUT,     /**< SIGTERM, wait 3 seconds, SIGKILL */
  227.     APR_JUST_WAIT,              /**< wait forever for the process to complete */
  228.     APR_KILL_ONLY_ONCE          /**< send SIGTERM and then wait */
  229. } apr_kill_conditions_e;
  230.  
  231. /* Thread Function definitions */
  232.  
  233. #if APR_HAS_THREADS
  234.  
  235. /**
  236.  * Create and initialize a new threadattr variable
  237.  * @param new_attr The newly created threadattr.
  238.  * @param cont The pool to use
  239.  */
  240. APR_DECLARE(apr_status_t) apr_threadattr_create(apr_threadattr_t **new_attr, 
  241.                                                 apr_pool_t *cont);
  242.  
  243. /**
  244.  * Set if newly created threads should be created in detached state.
  245.  * @param attr The threadattr to affect 
  246.  * @param on Thread detach state on or off
  247.  */
  248. APR_DECLARE(apr_status_t) apr_threadattr_detach_set(apr_threadattr_t *attr, 
  249.                                                    apr_int32_t on);
  250.  
  251. /**
  252.  * Get the detach state for this threadattr.
  253.  * @param attr The threadattr to reference 
  254.  */
  255. APR_DECLARE(apr_status_t) apr_threadattr_detach_get(apr_threadattr_t *attr);
  256.  
  257. /**
  258.  * Create a new thread of execution
  259.  * @param new_thread The newly created thread handle.
  260.  * @param attr The threadattr to use to determine how to create the thread
  261.  * @param func The function to start the new thread in
  262.  * @param data Any data to be passed to the starting function
  263.  * @param cont The pool to use
  264.  */
  265. APR_DECLARE(apr_status_t) apr_thread_create(apr_thread_t **new_thread, 
  266.                                             apr_threadattr_t *attr, 
  267.                                             apr_thread_start_t func, 
  268.                                             void *data, apr_pool_t *cont);
  269.  
  270. /**
  271.  * stop the current thread
  272.  * @param thd The thread to stop
  273.  * @param retval The return value to pass back to any thread that cares
  274.  */
  275. APR_DECLARE(apr_status_t) apr_thread_exit(apr_thread_t *thd, 
  276.                                           apr_status_t retval);
  277.  
  278. /**
  279.  * block until the desired thread stops executing.
  280.  * @param retval The return value from the dead thread.
  281.  * @param thd The thread to join
  282.  */
  283. APR_DECLARE(apr_status_t) apr_thread_join(apr_status_t *retval, 
  284.                                           apr_thread_t *thd); 
  285.  
  286. /**
  287.  * force the current thread to yield the processor
  288.  */
  289. APR_DECLARE(void) apr_thread_yield(void);
  290.  
  291. /**
  292.  * Initialize the control variable for apr_thread_once.  If this isn't
  293.  * called, apr_initialize won't work.
  294.  * @param control The control variable to initialize
  295.  * @param p The pool to allocate data from.
  296.  */
  297. APR_DECLARE(apr_status_t) apr_thread_once_init(apr_thread_once_t **control,
  298.                                                apr_pool_t *p);
  299.  
  300. /**
  301.  * Run the specified function one time, regardless of how many threads
  302.  * call it.
  303.  * @param control The control variable.  The same variable should
  304.  *                be passed in each time the function is tried to be
  305.  *                called.  This is how the underlying functions determine
  306.  *                if the function has ever been called before.
  307.  * @param func The function to call.
  308.  */
  309. APR_DECLARE(apr_status_t) apr_thread_once(apr_thread_once_t *control,
  310.                                           void (*func)(void));
  311.  
  312. /**
  313.  * detach a thread
  314.  * @param thd The thread to detach 
  315.  */
  316. APR_DECLARE(apr_status_t) apr_thread_detach(apr_thread_t *thd);
  317.  
  318. /**
  319.  * Return the pool associated with the current thread.
  320.  * @param data The user data associated with the thread.
  321.  * @param key The key to associate with the data
  322.  * @param thread The currently open thread.
  323.  */
  324. APR_DECLARE(apr_status_t) apr_thread_data_get(void **data, const char *key,
  325.                                              apr_thread_t *thread);
  326.  
  327. /**
  328.  * Return the pool associated with the current thread.
  329.  * @param data The user data to associate with the thread.
  330.  * @param key The key to use for associating the data with the tread
  331.  * @param cleanup The cleanup routine to use when the thread is destroyed.
  332.  * @param thread The currently open thread.
  333.  */
  334. APR_DECLARE(apr_status_t) apr_thread_data_set(void *data, const char *key,
  335.                                              apr_status_t (*cleanup) (void *),
  336.                                              apr_thread_t *thread);
  337.  
  338. /**
  339.  * Create and initialize a new thread private address space
  340.  * @param key The thread private handle.
  341.  * @param dest The destructor to use when freeing the private memory.
  342.  * @param cont The pool to use
  343.  */
  344. APR_DECLARE(apr_status_t) apr_threadkey_private_create(apr_threadkey_t **key, 
  345.                                                     void (*dest)(void *),
  346.                                                     apr_pool_t *cont);
  347.  
  348. /**
  349.  * Get a pointer to the thread private memory
  350.  * @param new_mem The data stored in private memory 
  351.  * @param key The handle for the desired thread private memory 
  352.  */
  353. APR_DECLARE(apr_status_t) apr_threadkey_private_get(void **new_mem, 
  354.                                                  apr_threadkey_t *key);
  355.  
  356. /**
  357.  * Set the data to be stored in thread private memory
  358.  * @param priv The data to be stored in private memory 
  359.  * @param key The handle for the desired thread private memory 
  360.  */
  361. APR_DECLARE(apr_status_t) apr_threadkey_private_set(void *priv, 
  362.                                                  apr_threadkey_t *key);
  363.  
  364. /**
  365.  * Free the thread private memory
  366.  * @param key The handle for the desired thread private memory 
  367.  */
  368. APR_DECLARE(apr_status_t) apr_threadkey_private_delete(apr_threadkey_t *key);
  369.  
  370. /**
  371.  * Return the pool associated with the current threadkey.
  372.  * @param data The user data associated with the threadkey.
  373.  * @param key The key associated with the data
  374.  * @param threadkey The currently open threadkey.
  375.  */
  376. APR_DECLARE(apr_status_t) apr_threadkey_data_get(void **data, const char *key,
  377.                                                 apr_threadkey_t *threadkey);
  378.  
  379. /**
  380.  * Return the pool associated with the current threadkey.
  381.  * @param data The data to set.
  382.  * @param key The key to associate with the data.
  383.  * @param cleanup The cleanup routine to use when the file is destroyed.
  384.  * @param threadkey The currently open threadkey.
  385.  */
  386. APR_DECLARE(apr_status_t) apr_threadkey_data_set(void *data, const char *key,
  387.                                                 apr_status_t (*cleanup) (void *),
  388.                                                 apr_threadkey_t *threadkey);
  389.  
  390. #endif
  391.  
  392. /**
  393.  * Create and initialize a new procattr variable
  394.  * @param new_attr The newly created procattr. 
  395.  * @param cont The pool to use
  396.  */
  397. APR_DECLARE(apr_status_t) apr_procattr_create(apr_procattr_t **new_attr,
  398.                                                   apr_pool_t *cont);
  399.  
  400. /**
  401.  * Determine if any of stdin, stdout, or stderr should be linked to pipes 
  402.  * when starting a child process.
  403.  * @param attr The procattr we care about. 
  404.  * @param in Should stdin be a pipe back to the parent?
  405.  * @param out Should stdout be a pipe back to the parent?
  406.  * @param err Should stderr be a pipe back to the parent?
  407.  */
  408. APR_DECLARE(apr_status_t) apr_procattr_io_set(apr_procattr_t *attr, 
  409.                                              apr_int32_t in, apr_int32_t out,
  410.                                              apr_int32_t err);
  411.  
  412. /**
  413.  * Set the child_in and/or parent_in values to existing apr_file_t values.
  414.  * @param attr The procattr we care about. 
  415.  * @param child_in apr_file_t value to use as child_in. Must be a valid file.
  416.  * @param parent_in apr_file_t value to use as parent_in. Must be a valid file.
  417.  * @remark  This is NOT a required initializer function. This is
  418.  *          useful if you have already opened a pipe (or multiple files)
  419.  *          that you wish to use, perhaps persistently across multiple
  420.  *          process invocations - such as a log file. You can save some 
  421.  *          extra function calls by not creating your own pipe since this
  422.  *          creates one in the process space for you.
  423.  */
  424. APR_DECLARE(apr_status_t) apr_procattr_child_in_set(struct apr_procattr_t *attr,
  425.                                                   apr_file_t *child_in,
  426.                                                   apr_file_t *parent_in);
  427.  
  428. /**
  429.  * Set the child_out and parent_out values to existing apr_file_t values.
  430.  * @param attr The procattr we care about. 
  431.  * @param child_out apr_file_t value to use as child_out. Must be a valid file.
  432.  * @param parent_out apr_file_t value to use as parent_out. Must be a valid file.
  433.  * @remark This is NOT a required initializer function. This is
  434.  *         useful if you have already opened a pipe (or multiple files)
  435.  *         that you wish to use, perhaps persistently across multiple
  436.  *         process invocations - such as a log file. 
  437.  */
  438. APR_DECLARE(apr_status_t) apr_procattr_child_out_set(struct apr_procattr_t *attr,
  439.                                                    apr_file_t *child_out,
  440.                                                    apr_file_t *parent_out);
  441.  
  442. /**
  443.  * Set the child_err and parent_err values to existing apr_file_t values.
  444.  * @param attr The procattr we care about. 
  445.  * @param child_err apr_file_t value to use as child_err. Must be a valid file.
  446.  * @param parent_err apr_file_t value to use as parent_err. Must be a valid file.
  447.  * @remark This is NOT a required initializer function. This is
  448.  *         useful if you have already opened a pipe (or multiple files)
  449.  *         that you wish to use, perhaps persistently across multiple
  450.  *         process invocations - such as a log file. 
  451.  */
  452. APR_DECLARE(apr_status_t) apr_procattr_child_err_set(struct apr_procattr_t *attr,
  453.                                                    apr_file_t *child_err,
  454.                                                    apr_file_t *parent_err);
  455.  
  456. /**
  457.  * Set which directory the child process should start executing in.
  458.  * @param attr The procattr we care about. 
  459.  * @param dir Which dir to start in.  By default, this is the same dir as
  460.  *            the parent currently resides in, when the createprocess call
  461.  *            is made. 
  462.  */
  463. APR_DECLARE(apr_status_t) apr_procattr_dir_set(apr_procattr_t *attr, 
  464.                                               const char *dir);
  465.  
  466. /**
  467.  * Set what type of command the child process will call.
  468.  * @param attr The procattr we care about. 
  469.  * @param cmd The type of command.  One of:
  470.  * <PRE>
  471.  *            APR_SHELLCMD     --  Anything that the shell can handle
  472.  *            APR_PROGRAM      --  Executable program   (default) 
  473.  *            APR_PROGRAM_ENV  --  Executable program, copy environment
  474.  *            APR_PROGRAM_PATH --  Executable program on PATH, copy env
  475.  * </PRE>
  476.  */
  477. APR_DECLARE(apr_status_t) apr_procattr_cmdtype_set(apr_procattr_t *attr,
  478.                                                   apr_cmdtype_e cmd);
  479.  
  480. /**
  481.  * Determine if the child should start in detached state.
  482.  * @param attr The procattr we care about. 
  483.  * @param detach Should the child start in detached state?  Default is no. 
  484.  */
  485. APR_DECLARE(apr_status_t) apr_procattr_detach_set(apr_procattr_t *attr, 
  486.                                                  apr_int32_t detach);
  487.  
  488. #if APR_HAVE_STRUCT_RLIMIT
  489. /**
  490.  * Set the Resource Utilization limits when starting a new process.
  491.  * @param attr The procattr we care about. 
  492.  * @param what Which limit to set, one of:
  493.  * <PRE>
  494.  *                 APR_LIMIT_CPU
  495.  *                 APR_LIMIT_MEM
  496.  *                 APR_LIMIT_NPROC
  497.  *                 APR_LIMIT_NOFILE
  498.  * </PRE>
  499.  * @param limit Value to set the limit to.
  500.  */
  501. APR_DECLARE(apr_status_t) apr_procattr_limit_set(apr_procattr_t *attr, 
  502.                                                 apr_int32_t what,
  503.                                                 struct rlimit *limit);
  504. #endif
  505.  
  506. /**
  507.  * Specify an error function to be called in the child process if APR
  508.  * encounters an error in the child prior to running the specified program.
  509.  * @param attr The procattr describing the child process to be created.
  510.  * @param errfn The function to call in the child process.
  511.  * @remark At the present time, it will only be called from apr_proc_create()
  512.  *         on platforms where fork() is used.  It will never be called on other
  513.  *         platforms, on those platforms apr_proc_create() will return the error
  514.  *         in the parent process rather than invoke the callback in the now-forked
  515.  *         child process.
  516.  */
  517. APR_DECLARE(apr_status_t) apr_procattr_child_errfn_set(apr_procattr_t *attr,
  518.                                                        apr_child_errfn_t *errfn);
  519.  
  520. /**
  521.  * Specify that apr_proc_create() should do whatever it can to report
  522.  * failures to the caller of apr_proc_create(), rather than find out in
  523.  * the child.
  524.  * @param attr The procattr describing the child process to be created.
  525.  * @param chk Flag to indicate whether or not extra work should be done
  526.  *            to try to report failures to the caller.
  527.  * @remark This flag only affects apr_proc_create() on platforms where
  528.  *         fork() is used.  This leads to extra overhead in the calling
  529.  *         process, but that may help the application handle such
  530.  *         errors more gracefully.
  531.  */
  532. APR_DECLARE(apr_status_t) apr_procattr_error_check_set(apr_procattr_t *attr,
  533.                                                        apr_int32_t chk);
  534.  
  535. #if APR_HAS_FORK
  536. /**
  537.  * This is currently the only non-portable call in APR.  This executes 
  538.  * a standard unix fork.
  539.  * @param proc The resulting process handle. 
  540.  * @param cont The pool to use. 
  541.  */
  542. APR_DECLARE(apr_status_t) apr_proc_fork(apr_proc_t *proc, apr_pool_t *cont);
  543. #endif
  544.  
  545. /**
  546.  * Create a new process and execute a new program within that process.
  547.  * @param new_proc The resulting process handle.
  548.  * @param progname The program to run 
  549.  * @param args the arguments to pass to the new program.  The first 
  550.  *             one should be the program name.
  551.  * @param env The new environment table for the new process.  This 
  552.  *            should be a list of NULL-terminated strings. This argument
  553.  *            is ignored for APR_PROGRAM_ENV and APR_PROGRAM_PATH types
  554.  *            of commands.
  555.  * @param attr the procattr we should use to determine how to create the new
  556.  *         process
  557.  * @param cont The pool to use. 
  558.  */
  559. APR_DECLARE(apr_status_t) apr_proc_create(apr_proc_t *new_proc,
  560.                                              const char *progname,
  561.                                              const char * const *args,
  562.                                              const char * const *env, 
  563.                                              apr_procattr_t *attr, 
  564.                                              apr_pool_t *cont);
  565.  
  566. /**
  567.  * Wait for a child process to die
  568.  * @param proc The process handle that corresponds to the desired child process 
  569.  * @param exitcode The returned exit status of the child, if a child process 
  570.  *                 dies, or the signal that caused the child to die.
  571.  *                 On platforms that don't support obtaining this information, 
  572.  *                 the status parameter will be returned as APR_ENOTIMPL.
  573.  * @param exitwhy Why the child died, the bitwise or of:
  574.  * <PRE>
  575.  *            APR_PROC_EXIT         -- process terminated normally
  576.  *            APR_PROC_SIGNAL       -- process was killed by a signal
  577.  *            APR_PROC_SIGNAL_CORE  -- process was killed by a signal, and
  578.  *                                     generated a core dump.
  579.  * </PRE>
  580.  * @param waithow How should we wait.  One of:
  581.  * <PRE>
  582.  *            APR_WAIT   -- block until the child process dies.
  583.  *            APR_NOWAIT -- return immediately regardless of if the 
  584.  *                          child is dead or not.
  585.  * </PRE>
  586.  * @remark The childs status is in the return code to this process.  It is one of:
  587.  * <PRE>
  588.  *            APR_CHILD_DONE     -- child is no longer running.
  589.  *            APR_CHILD_NOTDONE  -- child is still running.
  590.  * </PRE>
  591.  */
  592. APR_DECLARE(apr_status_t) apr_proc_wait(apr_proc_t *proc,
  593.                                         int *exitcode, apr_exit_why_e *exitwhy,
  594.                                         apr_wait_how_e waithow);
  595.  
  596. /**
  597.  * Wait for any current child process to die and return information 
  598.  * about that child.
  599.  * @param proc Pointer to NULL on entry, will be filled out with child's 
  600.  *             information 
  601.  * @param exitcode The returned exit status of the child, if a child process 
  602.  *                 dies, or the signal that caused the child to die.
  603.  *                 On platforms that don't support obtaining this information, 
  604.  *                 the status parameter will be returned as APR_ENOTIMPL.
  605.  * @param exitwhy Why the child died, the bitwise or of:
  606.  * <PRE>
  607.  *            APR_PROC_EXIT         -- process terminated normally
  608.  *            APR_PROC_SIGNAL       -- process was killed by a signal
  609.  *            APR_PROC_SIGNAL_CORE  -- process was killed by a signal, and
  610.  *                                     generated a core dump.
  611.  * </PRE>
  612.  * @param waithow How should we wait.  One of:
  613.  * <PRE>
  614.  *            APR_WAIT   -- block until the child process dies.
  615.  *            APR_NOWAIT -- return immediately regardless of if the 
  616.  *                          child is dead or not.
  617.  * </PRE>
  618.  * @param p Pool to allocate child information out of.
  619.  * @bug Passing proc as a *proc rather than **proc was an odd choice
  620.  * for some platforms... this should be revisited in 1.0
  621.  */
  622. APR_DECLARE(apr_status_t) apr_proc_wait_all_procs(apr_proc_t *proc,
  623.                                                   int *exitcode,
  624.                                                   apr_exit_why_e *exitwhy,
  625.                                                   apr_wait_how_e waithow,
  626.                                                   apr_pool_t *p);
  627.  
  628. #define APR_PROC_DETACH_FOREGROUND 0    /**< Do not detach */
  629. #define APR_PROC_DETACH_DAEMONIZE 1     /**< Detach */
  630.  
  631. /**
  632.  * Detach the process from the controlling terminal.
  633.  * @param daemonize set to non-zero if the process should daemonize
  634.  *                  and become a background process, else it will
  635.  *                  stay in the foreground.
  636.  */
  637. APR_DECLARE(apr_status_t) apr_proc_detach(int daemonize);
  638.  
  639. /**
  640.  * Register an other_child -- a child associated to its registered 
  641.  * maintence callback.  This callback is invoked when the process
  642.  * dies, is disconnected or disappears.
  643.  * @param proc The child process to register.
  644.  * @param maintenance maintenance is a function that is invoked with a 
  645.  *                    reason and the data pointer passed here.
  646.  * @param data Opaque context data passed to the maintenance function.
  647.  * @param write_fd An fd that is probed for writing.  If it is ever unwritable
  648.  *                 then the maintenance is invoked with reason 
  649.  *                 OC_REASON_UNWRITABLE.
  650.  * @param p The pool to use for allocating memory.
  651.  * @bug write_fd duplicates the proc->out stream, it's really redundant
  652.  * and should be replaced in the APR 1.0 API with a bitflag of which
  653.  * proc->in/out/err handles should be health checked.
  654.  * @bug no platform currently tests the pipes health.
  655.  */
  656. APR_DECLARE(void) apr_proc_other_child_register(apr_proc_t *proc, 
  657.                                            void (*maintenance) (int reason, 
  658.                                                                 void *, 
  659.                                                                 int status),
  660.                                            void *data, apr_file_t *write_fd,
  661.                                            apr_pool_t *p);
  662.  
  663. /**
  664.  * Stop watching the specified other child.  
  665.  * @param data The data to pass to the maintenance function.  This is
  666.  *             used to find the process to unregister.
  667.  * @warning Since this can be called by a maintenance function while we're
  668.  *          scanning the other_children list, all scanners should protect 
  669.  *          themself by loading ocr->next before calling any maintenance 
  670.  *          function.
  671.  */
  672. APR_DECLARE(void) apr_proc_other_child_unregister(void *data);
  673.  
  674. /**
  675.  * Notify the maintenance callback of a registered other child process
  676.  * that application has detected an event, such as death.
  677.  * @param proc The process to check
  678.  * @param reason The reason code to pass to the maintenance function
  679.  * @param status The status to pass to the maintenance function
  680.  * @remark An example of code using this behavior;
  681.  * <pre>
  682.  * rv = apr_proc_wait_all_procs(&proc, &exitcode, &status, APR_WAIT, p);
  683.  * if (APR_STATUS_IS_CHILD_DONE(rv)) {
  684.  * #if APR_HAS_OTHER_CHILD
  685.  *     if (apr_proc_other_child_alert(&proc, APR_OC_REASON_DEATH, status)
  686.  *             == APR_SUCCESS) {
  687.  *         ;  (already handled)
  688.  *     }
  689.  *     else
  690.  * #endif
  691.  *         [... handling non-otherchild processes death ...]
  692.  * </pre>
  693.  */
  694. APR_DECLARE(apr_status_t) apr_proc_other_child_alert(apr_proc_t *proc, 
  695.                                                      int reason,
  696.                                                      int status);
  697.  
  698. /**
  699.  * Test one specific other child processes and invoke the maintenance callback 
  700.  * with the appropriate reason code, if still running, or the appropriate reason 
  701.  * code if the process is no longer healthy.
  702.  * @param ocr The registered other child
  703.  * @param reason The reason code (e.g. APR_OC_REASON_RESTART) if still running
  704.  */
  705. APR_DECLARE(void) apr_proc_other_child_refresh(apr_other_child_rec_t *ocr,
  706.                                                int reason);
  707.  
  708. /**
  709.  * Test all registered other child processes and invoke the maintenance callback 
  710.  * with the appropriate reason code, if still running, or the appropriate reason 
  711.  * code if the process is no longer healthy.
  712.  * @param reason The reason code (e.g. APR_OC_REASON_RESTART) to running processes
  713.  */
  714. APR_DECLARE(void) apr_proc_other_child_refresh_all(int reason);
  715.  
  716. /** @deprecated @see apr_proc_other_child_refresh_all
  717.  * @remark Call apr_proc_other_child_refresh_all(APR_OC_REASON_RESTART)
  718.  * or apr_proc_other_child_refresh_all(APR_OC_REASON_RUNNING) instead.
  719.  * @bug The differing implementations of this function on Win32 (_RUNNING checks) 
  720.  * and Unix (used only for _RESTART) are the reason it will be dropped with APR 1.0.
  721.  */
  722. APR_DECLARE(void) apr_proc_other_child_check(void);
  723.  
  724. /** @deprecated @see apr_proc_other_child_alert
  725.  * @bug This function's name had nothing to do with it's purpose
  726.  */
  727. APR_DECLARE(apr_status_t) apr_proc_other_child_read(apr_proc_t *proc, int status);
  728.  
  729.  
  730. /** 
  731.  * Terminate a process.
  732.  * @param proc The process to terminate.
  733.  * @param sig How to kill the process.
  734.  */
  735. APR_DECLARE(apr_status_t) apr_proc_kill(apr_proc_t *proc, int sig);
  736.  
  737. /**
  738.  * Register a process to be killed when a pool dies.
  739.  * @param a The pool to use to define the processes lifetime 
  740.  * @param proc The process to register
  741.  * @param how How to kill the process, one of:
  742.  * <PRE>
  743.  *         APR_KILL_NEVER         -- process is never sent any signals
  744.  *         APR_KILL_ALWAYS        -- process is sent SIGKILL on apr_pool_t cleanup
  745.  *         APR_KILL_AFTER_TIMEOUT -- SIGTERM, wait 3 seconds, SIGKILL
  746.  *         APR_JUST_WAIT          -- wait forever for the process to complete
  747.  *         APR_KILL_ONLY_ONCE     -- send SIGTERM and then wait
  748.  * </PRE>
  749.  */
  750. APR_DECLARE(void) apr_pool_note_subprocess(apr_pool_t *a, apr_proc_t *proc,
  751.                                            apr_kill_conditions_e how);
  752.  
  753. #if APR_HAS_THREADS 
  754.  
  755. #if (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2)
  756.  
  757. /**
  758.  * Setup the process for a single thread to be used for all signal handling.
  759.  * @warning This must be called before any threads are created
  760.  */
  761. APR_DECLARE(apr_status_t) apr_setup_signal_thread(void);
  762.  
  763. /**
  764.  * Make the current thread listen for signals.  This thread will loop
  765.  * forever, calling a provided function whenever it receives a signal.  That
  766.  * functions should return 1 if the signal has been handled, 0 otherwise.
  767.  * @param signal_handler The function to call when a signal is received
  768.  * apr_status_t apr_signal_thread((int)(*signal_handler)(int signum))
  769.  */
  770. APR_DECLARE(apr_status_t) apr_signal_thread(int(*signal_handler)(int signum));
  771.  
  772. #endif /* (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2) */
  773.  
  774. /**
  775.  * Get the child-pool used by the thread from the thread info.
  776.  * @return apr_pool_t the pool
  777.  */
  778. APR_POOL_DECLARE_ACCESSOR(thread);
  779.  
  780. #endif /* APR_HAS_THREADS */
  781.  
  782. /** @} */
  783.  
  784. #ifdef __cplusplus
  785. }
  786. #endif
  787.  
  788. #endif  /* ! APR_THREAD_PROC_H */
  789.  
  790.